package sh.grapendaal.tsuushin.service;

import sh.grapendaal.tsuushin.core.RunnableCommand;

/**
 * The Command Service provides functionality to register a method which handles
 * a certain command triggered by a message from IRC. Commands are registered by
 * their trigger, which means the first word of a message. A trigger is prefixed
 * with a symbol to prevent normal sentences from triggering commands. The
 * prefix is configurable.
 */
public interface CommandService extends Service {
	/**
	 * Sets the prefix to use. The prefix needs to be in front of the trigger in
	 * order to activate a command.
	 * 
	 * @param prefix
	 *            The prefix character to use.
	 */
	void setPrefix(char prefix);

	/**
	 * Returns the currently configured prefix.
	 * 
	 * @return The current prefix.
	 */
	char getPrefix();

	/**
	 * Register a command with the Command Service.
	 * 
	 * @param trigger
	 *            The trigger which will activate the command.
	 * @param permission
	 *            The permission needed before being allowed to execute it.
	 * @param callback
	 *            The callback to invoke.
	 * @throws IllegalArgumentException
	 *             If there is already a command with the given trigger or if
	 *             the permission does not exist.
	 */
	void registerCommand(String trigger, String permission, RunnableCommand callback);

	/**
	 * Unregisters a command from the Command Service.
	 * 
	 * @param trigger
	 *            The trigger of the command to unregister.
	 * @throws IllegalArgumentException
	 *             If there is no command with the given trigger.
	 */
	void unregisterCommand(String trigger);

	/**
	 * Indicates whether a command with the given trigger currently exists.
	 * 
	 * @param trigger
	 *            The trigger to look for.
	 * @return Whether a command exists.
	 */
	boolean commandExists(String trigger);
}
